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This paper centers around an example program intended to 


OPERATING SYSTEM/360 CONVERSION AND demonstrate what can be included in a program for the 
| Operating System. Covered in detail is a description of 
INSTALLATION INFORMATION FOR PROGRAMMERS register conventions, including SAVE and RETURN macros; 


description of data sets, including Data Control Blocks and 
Data Definition statements; operator communication, includ- 
ing Write to Operator with Reply WTOR), Write to Operator 
(WTO), and usage of the PARAM entry in the EXEC job 
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(QSAM), most information can be applied to other access 
methods. | 
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INTRODUCTION 


$/360 Operating System offers the user a myriad of facilities and options. The 
system creates a new environment for data processing in that one of its main 
objectives is to maintain a constant work flow through the computing system. 
Keywords, such as turn-around time and throughput, are given new significance 
and meaning by minimizing setup time and computer time lost on job-to-job 
transition. The concept of a JOB is expanded from being one program only to 
a broader idea of a unit of work to be done encompassing many programs and 
several job steps. | 


However, with enlarged capability comes complexity. Most novices in the 
Operating System find that the volume of information written about the system 

is quite large. The evergrowing and constantly changing storehouse of informa- 
tion can be quite overpowering. Systems Engineers and IBM customers must 
somehow sift out of all of the information available what they must know in 
order to begin the programming effort. {t must be emphasized that there is 

NO substitute for reading the manuals. However, in an attempt to aid 
programmers get some idea of what is necessary to write a program for the 
Operating System, a skeleton example program may be very helpful. Often 

a concrete example helps the programmer to obtain a firm grasp on some of 

the things that he needs to know. An example may show many details which 

the programmer may otherwise overlook. If he sees something used, he may then 
return to his manuals to pursue the write-up of the macro or instruction in depth. 


Documentation and program organization become even more important as the 
complexity of a program grows. Therefore, included in the example program 
is an illustration of one way a program may be organized. We have found that 
the important thing with documentation is that whatever may be agreed upon 
should be strictly enforced if it is to be effective. 


The program was written for an installation which planned initially to use in 
most of its programs the Primary Control Program, the Queued Sequential Access 
Method (QSAM), the move mode of GET and PUT, and Assembler Language. 
These four limitations narrow the focus of this paper. 


A. PREREQUISITES 


1. A basic understanding of Assembler Language . 


2. Familiarity with Introduction to O/S, C28-6534, and Concepts and 
Facilities, C28-6535. 


B._SOURCE MANUALS 


Introduction 

Concepts & Facilities 
Job Control Language 
Control Program Services 
Data Management 


Linkage Editor 


C._TOPIC REFERENCES 


Topics are listed in order of presentation in paper. 


Topic 


QSAM 


OPEN 


CLOSE 


GET * Move Mode 


PUT * Move Mode 


DD Statements 


Generation Data Sets 
Data Control Block * QSAM 


SAVE 


RETURN 5 


Register Usage 


C28-6534 
28-6535 
28-6539 
28-6541 
28-6537 


C28-6538 
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(INTRO) 
(CF) 
(JCL) 
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(DM) 


(LE) 


Manual 
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(CPS) 
(SCL) 
(DM) 

(CPS) 
(CPS) 
(CPS) 
(CPS) 
(CPS) 


(CPS) 


Fopic. 

WTOR 

Event Control Block 
WTO 


PARAM in EXEC Card 


Control Characters ASA 


Machine Code 


Page 


112 


(CPS) 
(CPS) 
(CPS) 


(CPS) 
(JCL) 


(CPS) 


IBM 2821 Control Unit 424-3312 
§/360 Reference Data Card X20~-1703-3 


Il, PROGRAM EXAMPLE 


A. PROGRAM INTRODUCTION 


The following program example contains: 


1. 


C) 


Comment cards used to organize the program into basic sections 


Housekeeping 

Main Line 

Sub-routines 

Special Routines 

Constants, Accumulators, and Working Storage 
Input and Output Areas 

Data Control Blocks 


oma anwra 


The example is designed to use the Queued Access Method with 
the Move Mode of GET and PUT. 


There are three input files and four output files. Input from tape, 
card, and disk--Ovtput to tape, card, disk, and printer. 


Examples of WIOR, GET, PUT are given. 


Sd 
s 


ob 


SUGGESTED GENERAL PROGRAM OUTLINE PAGE 
PAGE 5 1 NAME 10 OP 16 OPERAND 
1 NAME 1O OP 16 OPERAND 72 . . 
CLOSE (DISKIN) 
CLOSE (CARDIN) 
| 7 CLOSE (TAPEQUT) 
PGM TITLE "GENERAL PROGRAM OUTLINE FOR asses CLOSE (DISKOUT) 
PROGL START CLOSE (CARDOUT) 
* *tkx HOUSEKEEPING *** | CLOSE (PRINTER) 
START SAVE (14512)5,PROG1 SAVE REGISTERS 144915,0-12 L 13,SAVF+4 LOAD ADDR OF YIUR SAVE AREA IN REG 13 
BALR 12,0 RETURN (14,12) RESTORE SAVED REGISTERS 
USING *,12 ; EJECT FND OF MAIN LINE SF PROGRAM 
USING *#4096,11 * *** SUBROUTINES *%# 
USING *+8192,10. SPACE 2 
ASTRSK L 11,ADCONL ' GETCARD GFT CARDIN,WRKREAND GET MOVE PLACFS A LOGICAL FECARI) 
L 10 ,ADCOGN2 . BR 3 “IN SPECTFIED WIRK AREA 
ST (13,SAVE+4 STORE ADOR OF CALLING PRIG*S SAVE AREA GETT© GET TAPFIN,WRKTPIN 
* IN YOUR SAVE AREA | BR 3 
LA 59 SAVE STORE ADDR OF YOUR SAVE AREA IN GETOSK GFT DISKIN sg WRKDSKIN 
ST 528(9,13) CALLING PROG*S SAVE AREA BR 3 ; 
8 BEGIN PUTTP PUT TAPEOUTWRKT?®9UT ALL PUT 239UTINES ARF PUT MOVE 
ADCONI Nc ACASTRSK +4096) : BR 3 | NATA MUST HAVE BEEN MOVED VIA 
ADCQN2 OC AC ASTRSK+8192) PUTDSK PUT DISKOUT,WRKOSKOY = PRAGRAMMING TO THE “UITPUT WIRK AREA 
EJECT BR 3 
* ) x**x MAIN LINE PROGRAM *** PUTC) PUT CAR NNUT, WRKPUNC4 
BESIN. OPEN CTAPEIN,CINPUT)) OPEN ALL DCBES BR 3 | 
OPEN (DISKIN, CINPUT)) WRITEPRT CP CRUNT, MAX TEST FOR NUMOQF 2 I LINES PRINTF ) 
OPEN (CARDIN, CINPUT)) RE SKIP 
NPEN (TAPEQUT,(9UTOUT)) MVI CNTRL»X*40! CARRTAGE CONTROL ©98 SPACE ONE LINE 
OPEN (DISKOUT,(GUTPUT)) % SEF IRE PRINTING - SEF 9,233 TPS 
OPEN (CARDOQUT, (QUTPUT)) AP COUNT, ONE PAICKOMENT LENE COUNTER bY NF 
UPFN (PRINTER, (9UTPUT)) BAL Se hUTPRT 
INSTRUCTIONS — BR 3 
INSTRUCTIONS . SKIP MVI CNTR gy X* 498 
BAL 3,GFETCAR9 BRANCH AND LINK TO COMMAN GFT RIUTINES ZAP COUNT, CLEAR CLEAR CHyNTe2 
BAL 3,GETOISK BAL S5yPUTPRT 
BAL 3,GETTP R HEADRTN 
INSTRUCTIONS PUTPRT Put PRINTER» WRKPRT 
| INSTRUCTIONS . MVC WREKEPRE»CLEARPRT CLFEAP PRINT AREA 
* ISSUE MESSAGE TO OPERATIR VIA CONSOLE BR 5 
NI FCRL,X*BF® HEADRTN MVI CNTRLyX*FL SKIP TO CHANNEL ING 
MSGL WIOR "GIVE CURRENT PROCESSING DATE*,CURDT,4,FCBL MVC WRKPRT#3207TP HEADING MVE HEANTUG Th WI2K AREA 
WATT ECRSECAL | BAL Se PUTPIRT 
* ANSWER IS PLACED IN STORAGE CURDT BR 3 
MSG2A4 NI ECR1,X*BFS CUECT 
MSG2 WINR "TS THIS A WEFKLY RUN!',ANS,3,ECB1 * *e* SPECTAL ROUTINES *** 
WAIT FCR=ECRL. ERROR WTO FAN INPUT QUTOUT FRRIP HAS OCCURE. - gus FYeze 
—-CLec ANS,NOT DEPENDING NN REPLY A’ BRANCH BR 14 | 
. BE DAILY 1S TAKEN * - eR CINSTANTS-ACCUMILATEUR S-VIRKING STI2AGE see 
CLC ANS,YES SPACE ? 
She WEEKLY * oR HALE WIRD ALIGNMENT #& 
B MSG2A REISSUE MESSAGE IF WRING REPLY 9S OH a 
INSTRUCTEONS * ** FULL WOR) ALIGNYENT. &* 
INSTRUCTIONS NS oF 
- BAL 3,HEADRTN SAVE NS 18F 
BAL 3, PUTTP BRANCH AND LINK TO COMMON PUT EC 31 OC Feoe 
BAL 3, PUTDSK * ee DVRLE WIRD ALTGNMENT &% 
BAL %3,PUTCD DS AD 
BAL 3yWRITEPRT SPACE ? 


CLOSE (TAPEIN) 


CLOSE ALL NC3"S 


NAME 


* 

* 

MAX 

CLEAR 

ANS 

CUROT 

* 

COUNT 
ONE 

* 

SWITCH 

* ‘2 

HEADING 


DC 
DC 


DC 
DC 


US 


WRKREAN 
COFLIL 
COFL2 
— COFLD3 


WRKTPTIN 
TPFLi1 . 
TPFLD2 


WRKDSKIN 
DKFLDL 


DKFLN2 


DKFLO3 . 


* 
WRKPUNCH 
PUFLDIL 
PUFLN2 
PUFLD3 . 


_ WRKTPOUT 
TPFLOLA 
- TPFLD2A 


“WRKDSKGU 
DKFLDLA 


10 OP 16 OPERAND 


** NO ALIGNMENT *4 
* CONSTANTS * 


DC X*050C* MAXIMUM NUMBER OF LINES PER PAGE 
DC X*Oc! 
DS CL3 WEEKLY OR DAILY RUN 
DS CL6 CURRENT NATE 
—%* COUNTERS * 
DC PL2'o? LINE COUNTER 
DC prye j 
* SWITCHES * 
DC —X*'008 ONE BYTE CAN REPRESENT MANY SWITCHES 
* HEADINGS * 
DC . C*HEADING® 
* EDIT WORDS * 
* ACCUMULATORS * 

INVOICE DESCRIPTIVE COMMENTS 
STATEMENTS DEFINE ACCUMULATORS AS ZERO 
STATEMENTS CONSTANTS WITH A GOID SIGN 

FILE . 
STATEMENTS 
STATEMENTS 

— * WORKING STGRAGE * 
STATEMENTS 
SPACE 2 

** LITFRALS ** 
LTORS - 
EJECT 
| xeEx INPUT/OUTPUT WORK AREAS *** 
SPACE 2 

** INPUT WORK AREAS ** 
Ns ICL38O 
DS CL?20 
Ns CL40 
DS CL 20 
SPACE ? 
OS OCL59 
OS CL25 
DS CL25 
SPACE 2 
OS OCL50 
OS CL 20 
NS CL 20 
DS CL10 
SPACE 2 

*& QUTPUT WORK AREAS ** 
DS OcL80 
DS CL20 
DS CL 40 
DS CL20 
SPACE 2? . 
os OCL50 
DS CL25 
OS CL25 
SPACE 2 
DS OCL50 
OS CL25 


PAGE 


1 NAME 10 OP 16 OPERAND 


DKFLDLA 
DKFLD2A 


CLEARPRT 
WRKPRT 
CNTRL 
PRT 

‘% 

* 

TAPEIN 
DISKIN 


CARDIN 


* 
TAPE QUT 


DISKIUT 
CARDOUT 


PRINTER 


DS 
DS 
SPACE 
DC 
DS 
DS 
DS 
FJECT 


SPACE 
pcB 


SPACE 
DCB 


SPATE 
DCB 


SPACE 


DCB 
SPACE 
DCB 
SPACE 
DCB 
SPACE 
DCB 


END 


CL25 
CL25 
? 
ct J 

OCL133 
Cil 

Ci 132 


*** DATA CONTROL BLOCKS *** 

2 

** INPUT DC3S ** 

NSCRG=PS,MACRFHEGM SDDNAMF=TAPEIN, 
EQDAD=ENDTAPE, SYNAD=ERROR 

2 

DSORG=PS_5MACRFH=GM pDUNAME=DISKING 
ENDAD=ENDDISK, SYNAD=ERROR 

2 

DSCRG=PS pMACRFHRSM,DINAME=CAP DIN, | 

EQ RPAD=ENDCARD, SYNAD=FFROR,E? IPT=SKO, 
RECFM=FBS,8LKSIZF=80,LRECL H2),8F TEXK=S, 
BUFND=2,8UFL=H30,BFALN=F 

? ‘ 
**x QUTPUT DCSS ** ; ; 
NSCRG=PS _MACRFHEPM,DINAMFZTAPFOUT, SYN ADEE 22 Dix 
2 . . 

DS ORG=PS, MACRE=EPM DONAMF EDT SKCUT, SYNAL EERO OE 
2 
DSORG=PS,4ACRF=HPM, JONAMFEC AR CUT, SYN ANET RETR 
2 

NSGRG=PS,4AC2F=HZPMNONAMF=EPRINTE 2 AF TEK HS, 
BUFND=1,B8UFL=133,8FALN=F ,EROPTH=ACC 

START 


PAGE 


~ 
N 


A 
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Ill. DESCRIPTION OF DATA SETS 


The two’ sources of information used to describe the data sets inthe. example 
program are the Data Definition (DD) statement and the Data Control Block 
(DCB). The following are provided. 
Data Definition Statements 
A. The DD cards as they might be coded. 
B. An example of the DD parameters chosen. 
Data Control Blocks 
A. The DCB's themselves are shown in the example program. 
B. A chart is given of all of the DCB parameters showing 
1. | What each entry is in the example program. 
2. | Which entries were actually put in the DCB and which ones 
were put in the DD card. 


A. DATA DEFINITION STATEMENTS 


1. INTRODUCTION 


_ Of the various parameters available in the DD statement, some fall into the category 


of being "necessary to make the job run." As an introduction to Operating System 
coding, a good approach was to concern the programmer in depth, at least initially, 
with only those options which he must include. This by no means indicates that the 
many other options are not useful, or, as the programmers progress, necessary fo 


obtain optimum efficiency. However, as a basic introduction, in keeping with 
the effort to give the programmer a feel for what can be included in a DD statement, 


the following DD statements were given as examples of what is needed to complete 
the description of the data sets used in the example program. 


2. DATA DEFINITION CONTROL CARDS 


ls Output Data Sets 


A. Disk 
1. 
//O\SKOUT DD 
// 
// 


Ve 
2. 


//DISKOUT DD 
// 
// 
// 

B. Tape 
//TAPEOUT DD 
// 
yf 
// 

C. Card 
//CARDOUT DD 
// 

7. 


Data set is catalogued 

DSNAME=MASTER(+1), DCB=(, EROPT=SKP, RECFM=FBS, 
BLKSIZE=250, LRECL=50, BFTEK=S, BUF NO=2, BUFL=250, 
BFALN=F), SPACE=(TRK, (50, 10),RLSE), 

VOLUME=REF=* . DISKIN, DISP=(, CATLG} 

Data set is passed 

DSNAME=MASTER, DCB=(, EROPT=SKP,RECFM=FBS, 
BLKSIZE=250, LRECL=50, BFTEK=S, BUFNO=2, BUFL=250, 
BFALN=F), SPACE=(TRK, (50,10),RLSE), 


VOLUMESREF=*. DISKIN, DISP=(, PASS) 


DSNAME=DETAIL(+1), DCB=(, EROPT=SKP, DEN=2, 
RECFM=FBS, BLKSIZE=250, LRECL=50, BFTEK=S, 
BUFNO=2, BUFL=250, BFALN=F), UNIT=TAPE, 
LABEL=(, SL,RETPD 0004), DISP=(, CATLG) 


DSNAME=CARD , DCB=(, EROPT=SKP, RECF M=FBS, 
BLKSIZE=80, LRECL=80, BFTEK=S, BUFNO=2, BUFL=80 


BFALN=F), UNIT=PUNCH 


D. Printer 


//PRINTER DD 


U7. 


DSNAME=REPORT, DCB=(, RECFM=FSA, BLKSIZE=1 33, 


LRECL=1 33), SYSOUT=A 


lf. Input Data Sets 


A. Disk 
//D\SKIN DD 
at 
// 
B. Tape 
7 
//TAPEIN DD 
// 
//— 
2. 
//TAPEIN DD 
{7 
jf 
Vie 
C. Card 
//CARDIN DD 
a 


DSNAME=MASTER(0), DC B=(, EROPT=SKP, RECFM=FBS, 
BLKSIZE=250, LRECL=50, BFTEK=S, BUF NO=2, BUFL=250, 


BFALN=F), UNIT=DISK, DISP=(OLD, CATLG) 


Data set is Sepalesuad. 

DSNAME=DETAIL(0), DCB=(EROPT=SKP, DEN=2, 
RECFM=FBS, BLKSIZE=250, LRECL=50, BFTEK=S, BUFNO=2, 
BUFL=250, BFALN=F), UNIT=TAPE, DISP=(OLD , CATLG) 
Data set is not catalogued 

DSNAME=DETAIL, DCB=(, EROPT=SKP, DEN=2,RECFM=FBS, 
BLKSIZE=250, LRECL=50, BFTEK=S, BUF NO=2, BUFL=250, 
BFALN=F), UNIT=TAPE, DISP=(OLD, CATLG), 


VOLUME=SER=1 23456 


* 


CARD DATA HERE 


1] 


3. EXPLANATION 


I. Output Data Sets 


A. 


DISKOUT 


When writing a new data set on disk, as done in the example program, 
the SPACE parameter is included. In our example, we reserved 50 tracks 
initially, specified that if there was insufficient space for the data set 

on these 50 tracks, space was to be allocated in increments of 10 tracks 
each. At the end of this step, if all of the space allocated was not used, 
the unused tracks were to be released (RLSE) for use by other data sets. 


Also specified was the request that the output MASTER(+1) data set be 
placed on the same physical unit as MASTER(0) defined in the DD state- 
ment DISKIN in this same job step. VOLUME=REF=* .DISKIN 


The disk output data set is to be made a new member of its data set. 
Therefore, the disk data set name is MASTER(+1). At the completion of 
this job step, it is to be catalogued. Since it is new, the first parameter 
of the DISP (disposition) does not have to be specified since NEW is 
assumed by default. When this data set is catalogued, it is automatically 
made the most current generation or 'son'. Accordingly, its element is 
changed from (+1) to (0) at disposition time and will be the input data 
set the next time the job step is run. At this time its serial number is 
recorded in the catalogue along with its element. 


An additional DD statement is included for DISKOUT showing the parameters 
required if this data set is not to be catalogued but instead passed to the 
next job step where more processing can be done and then the disposition 
specified. An example of where this method might be used is a job in which 
the first job step creates a file on disk, passes it to the next job step, and 
then this file is printed, possibly with some additional processing. 


TAPEOUT 


The tape output data set is also catalogued as described under the explana- 
tion of DISKOUT. DETAIL(+1) is to have standard labels and a retention 
period of 4 days. 


CARDOUT 


The parameters required to complete the DCB are shown. No disposition, 
DISP, is necessary because the data set is new, and it is to be deleted at 


the end of the job step. 


12 


PRINTER 


For a file that.is to be put on the printer, the DD parameter, SYSOUT, 
is used to specify the standard output class. At the sequential scheduler 
level, the UNIT parameter must be omitted if SYSOUT is specified. 


Input Data Sets 


A. 


DISKIN 


DISKIN is an OLD data set, for it was previously created. MASTER(0) 
is the data set name under which the disk data set is now catalogued. 
MASTER(0) indicates that the input should be the most current generation 
of the data set. When the disposition is executed at the end of the step, 
the generation number or ‘element’ of this data set will become (-1), 
indicating that it is now the 'father' version of the MASTER data set, 

the 'son' being the most current version. 


At System Generation time the addresses of the disk units were all equated 
to 'DISK'. Therefore, the DD statement does not have to specify a particu- 
lar device address, but may specify UNIT=DISK. In this way ‘drive inde- 
pendence’ is obtained. 


We complete the information needed for the DCB by specifying DCB= 
(parameter list). Note that in neither the DCB nor the DD statement is 
the DEVD or type of device parameter specified. This omission is made 
for an important reason. When the DCB is expanded, its length depends 
upon the type of device specified. If no DEVD parameter is given, the 
DCB is expanded to a maximum length. This is important when the data 
set being defined is a printer because a printer DCB expands into a shorter 
length than does a disk or tape device. Therefore, if a printer happened 
to be ‘down’, the printer data set could be temporarily written on disk or 
tape only if the DCB expansion assembled in the program were large enough 
to describe a disk or tape data set. Consequently, if you always allow the 
maximum length of the DCB by omitting the DEVD parameter, you may 
change the UNIT on the DD statement and be sure that the DCB is large 
enough to handle the file description. 


TAPEIN 


DETAIL is the data set name of the input tape. This data set is also 
catalogued. DETAIL is a generation data set and therefore the input 
data set name is DETAIL(0). It is important to note that the volume 
serial number does not have to be specified if the data set is catalogued 
because the serial number is kept by generation number in the catalogue 
with the data set name. In addition to the DD example of TAPEIN as a 
catalogued data set, another example is given of DETAIL as an uncata- 
logued data set. In this case, the programmer would have to call for 
the data set by serial number. 


As with the disk data set, we do not call for a specific unit but say 
UNIT=TAPE. 


14 
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is the only parameter allowed in the DD statement. The data should immedi - 


ately follow with a /* card at the end of the card data. 


The DCB is completed in the DD statement 


parameter. 
This data set is to come in via the input stream. Therefore, an asterisk, *, 


CARDIN 


C. 


IV. REGISTER CONVENTIONS 
A. EXPANSION OF SAVE AND RETURN MACROS 
+ Indicates Expansion 
(PROG 1) 
SAVE (14,12), ID 


DS OH 
STM ——-14, 12,1 2(13) 


The calling program must load register 13 with the address of its save area. 
Therefore, when your program (the called program) issues the SAVE macro, 


you are storing the calling program's registers in the calling programs save 
area. Note that the store multiple instruction uses register 13 as a base 


register with a displacement of 12. One register needs 4 bytes of storage. 


Calling program's save area: 1 word = 4 bytes 


SAVEAREA DS 18F  SAVEAREA is 18 full words 


WORD 1 WORD 2 WORD 3 WORD 4 WORD 5 WORD 6 
Addr.Called Register 14 Register 15 Register 0 


Prog's Savearea 


WORD 7 WORD 8 WORD 9 WORD 10 WORD 11 WORD 12 
Register 1] Register 2 Register 3 Register 4 Register 5 Register 6 


WORD 13) WORD 14 + +=WORD 15 WORD 16 WORD 17 WORD 18 
Register 7 Register 8 Register 9 Register 10 Register 11 Register 12 


The called program issues the following instructions: 


LA 5, SAVE 
ST 5, 8(13) 


Save is the address sf Jue called program ’s save area, This address is placed 
in the third word calling program's save area. Note that register 13 
still has the address of the calling program's save area and that cegister 13 


is used as a base register in the store instruction above. 
The called program issues the following instruction: 


ST 13, SAVE+4 
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This instruction places the contents of register 13 in the second word of 
its (the called program's) save area. This is necessary because the called 
program must reload register 13 with this address before it issues a return. 


L 13, SAVE+4 

RETURN (14,12) 

LM 14,12,12(13) restore the registers 
BR 14 


The expansion of the RETURN macro indicates clearly why the address of 
register 13, containing the address of the calling program's save area, 
must be stored and then reloaded. As with the SAVE macro, register 13 
is used as a base register. Note that the return branch is on the address 
in register 14 which had been loaded by the calling program before the 
called program was given control initially. 


Note that if the calling program is not a program as we may normally 
think of one, but is instead the control program, these conventions of 
linkage must still be observed. 


B. REGISTER RESTRICTIONS 


There are five registers which should not be used by the problem program. 
They are registers 0, 1, 13, 14, 15. 


V. COMMUNICATION WITH THE OPERATOR 


The three ways selected for communication with the operator are via the two macros, 


WTOR (Write to Operator with Reply) and WTO (Write to Operator), and the PARAM. 


entry in the EXEC job control card. 
A. WRITE TO OPERATOR WITH REPLY 
NI ECB1,X ‘BF 
MSG1 WTOR ‘GIVE CURRENT PROCESSING DATE', CURDT,6, ECB] 
WAIT ECB=ECBI 
CURDT DS CL6 
ECBI DC F'0' 
The WTOR macro must specify: 


1. The message to be written. 


2. The storage location reserved by the program where the control program 
is to place the answer. 


3. The length of the answer. 


4. The name of the Event Control Block (ECB) which the supervisor may use. 


This ECB must be defined as a full word zero constant. Format of the 
Event Control Block: 


0 1 2 | 3] 
PWC , Post Code 


[OY Se ee ed 


After the WTOR is issued, the programmer must issue a WAIT, if his program logic depends 
upon the reply. When the WAIT is issued, the supervisor sets bit zero of the ECB specified 
to 1. When the action has occurred, the supervisor issues a POST which turns bit zero of 
the ECB, the completion code to 1. The problem program is then given control. If is the 
programmer's responsibility to be sure that the completion flag is zero before the WTOR 


is issued again. An "And Immediate’, NI , instruction before the WTOR will always 
insure that the completion flag is zero. 
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B. WRITE TO OPERATOR 
MSG2 WTO "JULY 25 IS THE DATE! 


In the expansion of this macro, the message in quotes is found at the address 
MSG2+8. Therefore, if the programmer wanted to alter the message, he could 
move into this address the new information. For instance, suppose you had the 
current date in CURDT. To place this information in the message, you would 
write as follows: 


MVC MSG 2+8(7) ,CURDT 
MSG2 WTO ’ IS THE DATE’ 
C. PARAM 


PARAM='JULY 25! 


The above would be written in the EXEC card. The PARAM entry may be up 
to 40 characters. When the program is given initial control, Register 1 points 
to the address of the parameter list. The parameter list has the address of the 
data area where the control program has placed "JULY 25', 


_.+ +-full word boundary 


” Parameter list 
A . A. A AAA=address of data area 
Register | 
Gorrie half word boundary Data Ares 
ew July 25 cc=count of characters 
nnn (max 40) 


The programmer would write as follows: 


L 5,0(1) Load contents of Reg. 1 into Reg. 5 
Reg. 5 now has address of data area 
MVC  CURDT, 2(5) 


These instructions would place the information put in the PARAM entry into the 
reserved core location CURDT. 
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VI. CONTROL CHARACTERS 


Instead of using the CNTRL macro and PRTOV macro for direct printer control, 


_control characters may be used. One advantage of this is that it enables the 


print file to be stored temporarily on disks and then later written on the printer 
as a SPOOL operation, There are two choices available for control characters. 


A. ASA 


The example program used ASA control characters as follows: 


blank Space one line before printing 
0 Space two lines before printing 


Space three lines before printing 


+ Suppress space before printing 
1 Skip to channel 1 
2-C Skip to channel N 


When these characters are used the RECFM specified in either the DCB or 


DD statement must be 'FSA’. 


Note that the ASA codes present one drawback in that they do not allow 
spacing or skipping offer print. 


B. Machine Codes 


To obtain space or skip after print, machine codes should be used. 


The RECFM would then be 'FM', 


Hex. Operation 

01 Write, no space 

09 Write, space | after print 

VW | Write, space 2 after print 

19 Write, space 3 after print 

89 Write, skip to channel 1 after print 
91 Write, skip to channel 2 after print 
99 Write, skip to channel 3 after print 
Al Write, skip to channel 4 after print 
AY Write, skip to channel 5 after print 
Bl Write, skip to channel 6 after print 
B9 Write, skip to channel 7 after print 
Cl Write, skip to channel 8 after print 
C9 Write, skip to channel 9 after print 


DI Write, 
D9 Write, 
E] Write, 


skip to channel 10 after print 
skip to channel 11 after print 
skip to channel 12 after print 
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Vil, DOCUMENTATION 


A. PROGRAM ORGANIZATION 


The program example illustrates one suggested way to organize the various 
sections of a program. 


1. 


A TITLE card is used to 
a. Identify the assembly listing. 


b. Provide identity for the object deck from the name field of 
the TITLE card. 


HOUSEKEEPING should contain all of the necessary register set-up 
including SAVE and base register allocation, 


The MAIN LINE PROGRAM contains the basic logi = flow ending with 
RETURN. 


SUBROUTINES may be either closed or open. A closed routine branches 
ona register. An open routine branches to a specific address. GET and 
PUT macro instructions are put under subroutines. The GET and PUT are 
placed here so that, no matter how many different places in the program a 
given file may be read or written, the macro is expanded only once. 


SPECIAL ROUTINES may consist of SYNAD routines to handle I/O errors. 
In the example program ERROR is the SYNAD routine. It is suggested that 
a common error routine be written for the installation as a whole which 
can be inserted in each program with little, if any, modification. 


CONSTANTS, ACCUMULATORS AND WORKING STORAGE is a general 
division which can be further subdivided to suit the needs of the program. 
It is suggested that all areas which need special alignment such as full or 
half word be grouped together and labeled as such. 


Accumulators, as a general rule, should be defined as zero with a good 
sign. They may be grouped according to the level, be it minor, inter- 
mediate or major (invoice, client, file). Each accumulator should be 
followed by a comment which clearly explains what it is used for even 
though the name of the accumulator may be neumonic. 


Switches may be grouped together. It is suggested that bit switches be 
used instead of byte switches in order to conserve core. However, this 
means that comment cards should explain specifically what each bit 
represents. 
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7. INPUT AND OUTPUT WORK AREAS need to be grouped together. B. PROGRAM FOLDER 
Each work area should clearly indicate which DCB it applies to. 


oes 1. TABLE OF CONTENTS 
8. DCB’s are the last division. They are organized by input and output. re 


. . A program folder should contain all of the information which is needed to 
The use of EJECT and SPACE instructions to the assembler help to organize the lectibe the program. Suggested contents are: 
source listing into a more readable format. 


1. Brief program summary 

2. Configurator 

3. Layouts or formats of input and output records 

4, A sample printout 

5. Ageneral block diagram 

6. The source or assembler listing 

7. Acopy of the operator's instruction sheet 

8. Samples of all job control cards 

9. History of changes 
The history of changes is a running documentary beginning with the original 
programmer and date. As a change is made to the program, the name of the 
programmer who made the change, the date, and a brief synopsis of the change 


made is entered, 


The configurator is a handy way of giving a picture of the input and output units 
used by the program. A configurator of the sample program is included in this paper. 
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oe. . 


2. CONFIGURATOR 


Circle the appropriate direction and darken the arrow. 


i i . - 2 as fa * 
Ny fs ) (= Nay Track | 


< 
ee 
a as 


' Reader ; 


av 


Printer 


Central 


Processing Unit 


Printer 
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C. NAMING CONVENTIONS 


The method of naming jobs, programs and data sets varies greatly from installation 
to installation. With O/S 360 some way of relating jobs to job steps, and programs 
and of relating DD statements to DCB's is not only helpful, but almost mandatory. 
Within one installation there are many types of applications programmed for the 
computer, i.e., PAYROLL, DEMAND DEPOSIT ACCOUNTING, SAVINGS. 
These applications offer a natural way of organizing programs. For instance, a 
program written for PAYROLL would begin with the key letters 'PAY'. 


There are three types of control cards needed--the JOB card, the EXEC card or 
job step card, and the DD cards. In the card you need a name with a maximum 
of 8 characters, which becomes the job name or step name. Since a step is part 
of some job, it easily follows that the stepname should relate to the jobname. 
The following is one suggested naming convention for JOB and EXEC cards: 


JOB card 
Application Job Number Step Number 
(PAY 1-F 0 
DDA 
SAV 
Example: Ist job in payroll PAY 10 
2nd job in savings SAV 20 
11th job in demand deposits DDABO 
EXEC card 7 
Application Job Number Step Number 
PAY 1-F 1-F 
DDA 
SAV 
Example: Ist step in Ist job in payroll PAY11 
3rd step in 2nd job in savings SAV23 


15th step in 11th job in demand deposit DDABF 


The name of the DD card must be specified in the DCB parameter, DDNAME. 
Therefore, to simplify the naming process, it is suggested that the name of the 
DD statement be the same as the 

name of the corresponding DCB in the program. 


Programs relate in most cases to one job step. Therefore, their names can relate 
to the step name as follows: 
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Application Job Number Step Number neumonic 


PAY 1-F 1-F 
DDA 
SAV 
Example: the posting program which is used by the Ist step 
in the Ist job in payroll 
PAY11PST 


the dividend program which is used by the 3rd step 
in the 2nd job in savings 
SAV23DIV 
the statement program which is used by the 15th step 
in the 11th job in demand deposit accounting 
DDABFSTM 


There is no attempt to relate these data set names to a specific job or program since | 
one data set may be used by many different jobs. 


For temporary data sets a T prefix on the data set name helps to separate these data 
sets from those which are permanent. 
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